This section describes QuArK distribution policy, tools and methodology.

QuArK has two types of releases: distributions and snapshots.

1. Distributions are released through the SourceForge Release System. A distribution consists of the following files:
   •  quark-win32-version.exe  - a Nullsoft Scriptable Install System executable containing the QuArK Windows binaries with a bundled Python micro-distribution and the Infobase.
   •  quark-src-version.zip  - a zip archive containing full exports of the  infobase ,  runtime  and  source  CVS modules.
   •  quark-help-version.zip  - a zip archive containing the compiled Infobase.
   You will need to have "Release Technician" permissions on the QuArK SourceForge project to be able to release a distribution.

   N.B. that version numbers are in the format  #.#.#state#  where 'state' can be one of 'rel', 'beta', or 'alpha'. The numbers before the current state are the major and minor versions, and the number after the state is the release number at that version/state. Examples:

   •  6.4.0alpha1 . Note also that version numbers should be unique.
   •  6.3.0rel4 
2. Snapshots are released on QuArK's SourceForge webspace ( http://quark.sourceforge.net). A snapshot consists of the following files:
   •  quark-win32-date.zip  - a zip file containing the QuArK Windows binaries with a bundled Python micro-distribution and the Infobase.
   •  quark-src-date.zip  - a zip file containing full exports of the  infobase ,  runtime  and  source  CVS modules.
   •  quark-help-date.zip  - a zip file containing the compiled Infobase.
   You will need to have access to the QuArK project's SourceForge webspace (i.e. a SourceForge shell account is required) to be able to release a snapshot.

   N.B. that dates should be in the format  YYYYMMDD .

Typically, QuArK snapshots are released every two weeks, although this may vary depending on how much work is being done. If two weeks go by with very little CVS activity, there won't be much point in doing a release; equally, if things are frenetic, it's likely we'll do snapshots more frequently.

Distributions are done on a much less frequent basis, because they require much more work on the part of whoever's doing the releases.

Here's the process you might follow to prepare and release a snapshot. Before you'll be able to follow the process outlined below, you'll need to read Introduction to SSH on SourceForge.net, and set up your system with PuTTY accordingly.

I'm going to assume that the date is 31st August 2007.

1. Build a QuArK binary with  PYTHON_BUNDLED  and compress it using UPX (available from http://upx.sourceforge.net/). You should use:

   > upx -9 --compress-icons=0 QuArK.exe

2. Use PSFTP to upload it to your user account on the shell server. Also upload the latest micro-Python files.

   > psftp shell.sourceforge.net
   psftp> put QuArK.exe
   psftp> put micro-python22.zip
   psftp> quit

3. PuTTY to the shell server and change to the QuArK directory.

   > putty shell.sourceforge.net
   $ cd /home/groups/q/qu/quark

4. Do a CVS export of the  infobase ,  runtime  and  source  modules.

   $ cvs -z3 -Q -d:pserver:anonymous@cvs1:/cvsroot/quark export -rHEAD infobase
   $ cvs -z3 -Q -d:pserver:anonymous@cvs1:/cvsroot/quark export -rHEAD runtime
   $ cvs -z3 -Q -d:pserver:anonymous@cvs1:/cvsroot/quark export -rHEAD source
   

   We use the CVS export command because that way we get a clean copy of the files without the CVS folders.
5. Extract the micro-Python files.

   $ unzip -q ~/micro-python22.zip

6. Create folders for each of the three files you're going to need in the end.

   $ mkdir quark-help-20070831
   $ mkdir quark-src-20070831
   $ mkdir quark-win32-20070831

7. Build the Infobase, and copy the output to where it's needed.

   $ mkdir quark-win32-20070831/help
   $ cd infobase
   $ python ./build.py -local
   $ cp -r output/* ../quark-help-20070831/
   $ cp -r output/* ../quark-win32-20070831/help
   $ rm -rf output
   $ cd ..

8. Put together the files for the source snapshot.

   $ cp -r infobase/ quark-src-20070831/
   $ cp -r source/ quark-src-20070831/
   $ cp -r runtime/ quark-src-20070831/
   $ cp -r micro-python22/ quark-src-20070831/

9. Put together the files for the Windows binary snapshot.

   $ cp ~/QuArK.exe quark-win32-20070831
   $ cp -r runtime/* quark-win32-20070831/
   $ rm -f quark-win32-20070831/dlls/d3dxas.dll
   $ rm -f quark-win32-20070831/dlls/readme.txt
   $ cp micro-python22/dlls/python.dll quark-win32-20070821/dlls/
   

10. Zip up the files.

    $ zip -9rq quark-help-20070831.zip quark-help-20070831/
    $ zip -9rq quark-src-20070831.zip quark-src-20070831/
    $ zip -9rq quark-win32-20070831.zip quark-win32-20070831/

11. Remove working directories.

    $ rm -rf source/ infobase/ runtime/ quark-src-20070831/
    $ rm -rf quark-help-20070831/ quark-win32-20070831/

12. Move our snapshot files into the website's download directory and generate MD5 checksums.

    $ mv quark*.zip htdocs/download/
    $ cd htdocs/download/
    $ md5sum quark-help-20070831.zip > quark-help-20070831.zip.md5
    $ md5sum quark-src-20070831.zip > quark-src-20070831.zip.md5
    $ md5sum quark-win32-20070831.zip > quark-win32-20070831.zip.md5
    

13. You now need to edit the  /home/q/qu/quark/htdocs/index.html  file to add the new snapshot. Use the text editor of your choice - I generally use Emacs.

    It's also a good idea only to have four snapshots on the site at a time, so as to be sure not to exceed the storage quota. So delete the oldest snapshots if you need to.

Ideally, snapshots would eventually have an NSIS installer for the binary release.

TODO: write a script to automate the above process fully and upload it to the shell server. Make it a cron job?

Before you'll be able to follow the process outlined below, you'll need to read Introduction to SSH on SourceForge.net, and set up your system with PuTTY accordingly. I'm going to assume that you're running Windows.

In preparation for creating a distribution, you'll need to carry out a couple of preliminary steps.

1. Download and install Nullsoft Scriptable Install System (NSIS) 2.0 beta 4 or higher from http://nsis.sourceforge.net.
2. Checkout the  utils  module from QuArK CVS on SourceForge. This module contains the scripts and other files you'll need to be able to create the distribution.
3. Make sure you have access permissions to work with the SourceForge release system.

So, once you've decided that you're ready to create a distribution, here's what you do.

1. First, work out what the version number is for this distribution (see 'QuArK Release Policy'). You'll probably need to discuss with other developers to decide what the state is going to be and whether to increment the the minor version, but for the sake of argument lets say the version number you come up with is '6.4.1beta3'.
2. Most of creating a distribution is similar to creating a snapshot. First, do steps 1 to 11 of 'Releasing a Snapshot', with the difference that you name the files with the '6.4.1beta3' instead of the date, so  quark-win32-20070831  becomes  quark-win32-6.4.1beta3 .
3. Move your  quark-win32-6.4.1beta3.zip  to your shell server home directory.

   $ mv quark-win32-6.4.1beta3.zip ~/

4. Upload the source and help distributions to the release system's incoming directory.

   $ ftp
   ftp> open upload.sourceforge.net
   ftp> binary
   ftp> put quark-src-6.4.1beta3.zip
   ftp> put quark-help-6.4.1beta3.zip
   ftp> quit

5. Use PSFTP to download your  quark-win32-6.4.1beta3.zip  to your own computer.

   > psftp shell.sourceforge.net
   psftp> get quark-win32-6.4.1beta3.zip
   psftp> quit

6. Create a new directory somewhere on your system - let's say  C:\qrkinstall  - and copy the files from your checkout of  utils/nsis-dist-tools  to that directory. You will need:
   • install_header.bmp
   • install_splash.bmp
   • license.rtf
   • QuArK.nsi
   Use your favourite archiving program to extract the files from your  quark-win32-6.4.1beta3.zip  to  C:\qrkinstall\quark .
7. Open  QuArK.nsi  and edit the "QuArK Version" section as applicable. In this case, you'd want it to look something like this:

   !define QRK_MAJOR_VER 6.4
   !define QRK_MINOR_VER 1
   !define QRK_STATE "beta"
   !define QRK_RELEASE 3
   

   Save and close.
8. Right click on  QuArK.nsi  in Windows Explorer and select "Compile NSI (with bz2)". Please use BZ2 compression, as it provides much better compression ratios that ZIP (the default).
9. Upload the newly created  quark-win32-6.4.1beta3.exe  to the incoming directory for the SourceForge release system.

   > ftp
   ftp> open upload.sourceforge.net
   ftp> binary
   ftp> put quark-win32-6.4.1beta3.exe
   ftp> quit

10. All the distribution files ( quark-src-6.4.1beta3.zip ,  quark-help-6.4.1beta3 , and  quark-win32-6.4.1beta3 ) are now ready for you to process them through the SourceForge release system. Don't forget that the release system upload directory is flushed every 24 hours.

Once you've finished doing the release, it would probably be a good idea to update the main QuArK website and to post an announcement to the quark, quark-news and quark-python mailing lists, as well as adding links to the snapshot webpage.

TODO: Add instructions for actually using the SourceForge release system.